home *** CD-ROM | disk | FTP | other *** search
/ Programmer Power Tools / Programmer Power Tools.iso / dirutl / di11.arc / DI.DOC < prev    next >
Text File  |  1988-04-02  |  19KB  |  303 lines
  1.      Documentation for DI: Directory Listing Utility  v 1.1
  2.  
  3.             by  John H. DuBois III
  4.  
  5.      DI is a directory listing program, similar to to the DOS command DIR.
  6. However, it has several extensions beyond the capabilities offered by DIR.
  7. These extensions are:
  8.    * More than one file specification can be given on the command line.
  9.    * Filespecs can have wildcards in the directories of a path as well
  10. as the file name, so that one filespec can specify mulitiple directories
  11. to be searched.
  12.    * Implicit wildcards in the path are converted to explicit wildcards.
  13.    * A recursive search of directories can be specified.
  14.    * The attributes of directory entries to search for can be specified.
  15.    * Hidden, system, and volume label entries can be listed.
  16.    * The files found in each directory can be sorted according to various
  17. criteria; groups of entries that are not differentiated by the selected
  18. criteria are then sorted by filename.
  19.    * The total space used by the files listed in each dir can be printed.
  20.    * The printing of the free space on the device can be toggled off.  Most
  21. hard drives take several seconds to determine the amount of free space; this
  22. option can avoid the delay.
  23.    * The printing of headers can be toggled off.  In this case only the file
  24. listing will be printed.  This is often used when the output of DI is being
  25. piped to some other program.
  26.    * In addition to "wide" and "long" listings, entries can be listed
  27. with their full path, without a header for each directory listed.
  28.    * When dirs are listed in "long" form, file attributes are listed along
  29. with the usual information.  When dirs are listed in "wide" form, the number
  30. of names printed on each line can be specified.  When dirs are listed in
  31. "wide" or "full path" form, a backslash is appended to entries that are
  32. subdirectories to indicate this.
  33.    * Unless printing of subdirectory entries is specifically requested (rather
  34. than by default) the "." and ".." entries in subdirectories are not printed.
  35.    * Defaults for file attributes to search for and listing specifications
  36. can be given by setting an environment variable.
  37.    * If the listing is paused, pressing any key except <space> or 'q' will
  38. cause only one line to be printed (and one line scrolled off) before pausing
  39. again.  If 'q' is pressed, the listing is aborted.
  40.    * The pause message and all error messages are sent to the screen even if
  41. output is redirected.
  42.  
  43.      File Specifications
  44.  
  45.      Multiple Filespecs:
  46.      If more than one filespec is given on the command line, each filespec
  47. will be acted on in turn, from left to right.
  48.      Directory names with wildcards:
  49.      If a component of a path other than the trailing name contains wildcards,
  50. the path is expanded to multiple paths, where the wildcard-containing dir
  51. name has been replaced with all matching dirs.  For example, if TEMP, TEXT,
  52. and TURBOC are children of the root directory, the filespec  \t*\*.*  would be
  53. expanded to  \TEMP\*.* \TEXT\*.* \TURBOC\*.* .  The contents of all three dirs
  54. would be printed in turn, just as though you had given all of them on the
  55. command line.  This filespec would NOT have caused ordinary entries in the root
  56. directory that started with t to be listed.
  57.      Similarly, the filespec  \*.*\*.*\*.c (or, as the next section
  58. demonstrates, simply  \\\.c ) will cause the entries of all third-level dirs
  59. with the file extension ".c" to be printed.
  60.      Implicit Wildcards:
  61.      A file or directory name given in a path contains implicit wildcards
  62. if a file name or file extension is not given.  A directory name is assumed
  63. to exist between every pair of backslashes, and a directory or file name
  64. after the trailing backslash.  If the path has no backslashes it is assumed
  65. to be a single name.
  66.      Implicit wildcards will be replaced with explicit wildcards.  For
  67. example,  c:\t*\\.exe  is expanded to  c:\t*.*\*.*\*.exe .  To specify a
  68. name that does not have an extension without having it expanded to include
  69. a wildcard extension, end it with a dot.  "NAME." will not be expanded to
  70. "NAME.*".  If  \temp  is a directory, it will be expanded to  \temp\*.* ;
  71. otherwise it will be expanded to  \temp.* .
  72.      Recursive search:
  73.      If the recursive search flag (/c) is given, each filespec will be
  74. split into target directory and file name.  For example,  \turboc\progs\*.c
  75. is split into  \turboc\progs\  and  *.c .  All descendant directories of the
  76. target dir are then found, and are added to the list of dirs to search with
  77. the orignal file name as filename.  For example,  \turboc\progs\*.c  might
  78. be expanded to
  79.  \turboc\progs\*.c  \turboc\progs\emulator\*.c  \turboc\progs\ustop\*.c .
  80. If  \turboc\progs\emulator  or  \turboc\progs\ustop  had had child dirs, they
  81. would have been added to the list as well.  Thus,  the arguments  \.com /c
  82. specify a recursive search starting at the root for all .com files.  All
  83. .com files on the disk (except hidden ones) will be listed.  Similarly,  \ /c
  84. will produce a complete listing of all non-hidden files on the disk.
  85.      Each time the flag is given, it toggles recursive search.  If it was off,
  86. it is turned on; if on, off.  The final value determines whether a recursive
  87. search of the filespecs is done.
  88.      Order of expansion:
  89.      Paths containing wildcards in directories are first expanded to multiple
  90. paths.  Then, if recursive search has been specified, the descendant dirs of
  91. all target dirs are added.
  92.  
  93.      All of the above path expansions cause each new paths to be added to the
  94. list of directories to search, just as though they were given on the command
  95. line.  Thus,  \.com /c  will cause a listing all directories, even if they
  96. do not have any .com files.  Directories with no .com files will simply report
  97. "0 matching files.".  If only a few dirs contain .com files, most of the
  98. printout will be reports of "0 matching files".  In this case, the "full path"
  99. type listing (described later) can be useful.
  100.  
  101.      The following describes flags that are used to specify the type of search
  102. and listing.  Flag groups are preceded by one of the flag specifiers '/' and
  103. '-'.  The particular flag specifier used does not have any significance. All
  104. command line arguments that do not begin with one of those characters are
  105. assumed to be filespecs.  DOS does not recognize '-' as a flag specifier, so it
  106. must be preceded by a space.  For example, DI/c is legal, but DI-c is not. The
  107. latter must be entered as DI -c .
  108.      All flags in one command line argument are considered to be part of a
  109. group.  The positioning of flag groups on the command line relative to file
  110. specs has no significance.  Flags can preceed filespecs, succeed them, or be
  111. interspersed with them.  The specific group that a flag is put in has
  112. significance only for attribute flags.  For example, h, s, and v  are attribute
  113. flags;  w, p, and 6 are not.  Therefore,  DI /wp /6  will have the same
  114. effect as  DI /w /p6 , but DI /hs /v will not have the same effect as DI /hsv .
  115. Attribute flags can be given in the same group as non-attribute flags; the
  116. attribute term that is produced from the group will be the same as if only
  117. attribute flags were given and the other flags will be interpreted the same as
  118. if they had been given by themselves.
  119.      The order of flags within groups, and the order of groups on the command
  120. line, has significance only when mutually exclusive flags are given.  In this
  121. case, the last flag given will hold and the previous (conflicting) flag will
  122. be cancelled.  For example, /x and /t are mutually exclusive because they
  123. specify different sorts.  DI /xt will have the same effect as DI /t .  All
  124. flags that are given on the command line affect all filespecs that are given
  125. on the command line.
  126.  
  127.      Attributes:
  128.      Files have six attributes: Hidden, system, read-only, volume, directory,
  129. and archive.  Hidden files are not listed by DIR and are not acted on by most
  130. DOS commands.  System files have the same characteristics as hidden files and
  131. are part of DOS.  Read-only files can not be erased or overwritten, but can
  132. be renamed.  The volume attribute specifies that the entry is the volume label.
  133. The directory attribute specifies subdirectories and the entries that give the
  134. name of the current and parent dirs ("." and "..").  The archive attribute
  135. indicates files that have been added or altered since the last backup.  The
  136. archive attribute is set on all floppy files.
  137.      Files that have or do not have specific attributes can be searched for
  138. with the first letter of the attribute.  The letter, in lower case ('h', 's',
  139. 'r', 'v', 'd', or 'a'), specifies that files must have the attribute to match.
  140. In upper case ('H', 'S', 'R', 'V', 'D', or 'A'), it specifies that that files
  141. must not have the attribute to match.  For example,  /hsR specifies that only
  142. files that are hidden and system and are not read-only should be listed. The
  143. 'e' flag specifies that Everything should be printed, including hidden, system,
  144. and volume entries.
  145.      Flags that specify a number of attributes that an entry must have all of
  146. in order to be listed must be given in a single group.  More than one group of
  147. attribute flags can be given.  In this case, an entry will be listed if it
  148. matches any of the groups.  For example,  /hsR /dA  will cause a listing of
  149. all entries that are hidden, system, and not read-only, OR that are directories
  150. without the archive bit set.
  151.      If hidden files, system files, and the volume label are not specifically
  152. requested, they will not be listed.  If directory entries are not specifically
  153. requested, the "." and ".." entries in subdirectories are not printed.  Also,
  154. the "." and ".." entries will not be printed if a recursive listing is done,
  155. even if directories are specified (to make a recursive listing of directories
  156. cleaner).
  157.  
  158.      Sorting:
  159.      Directory entries can be sorted by directory attribute, file extension,
  160. time and date, or size.  Groups of entries that are not differentiated by
  161. this first sort are then sorted in alphabetical order by file name.
  162.      The 'i' flag specifies sort by dIrectory attribute.  When a directory is
  163. listed, entries that are subdirectories will be printed first, then ordinary
  164. files.
  165.      The 'x' flag specifies sort by file eXtension.  Entries without a file
  166. extension will be listed first.  Then, files will be listed in alphabetical
  167. order of their extensions.
  168.      The 't' flag specifies sort by Time and date.  Entries are listed in order
  169. of those with the earliest time and date to those with the latest.
  170.      The 'z' flag specifies sort by siZe.  Entries are listed in order of
  171. smallest to largest.  If subdirectory entries or the volume label are found in
  172. the directory, they will be listed first since they have a size of 0.
  173.      The 'n' flag specifies that no preliminary sort is to be done; the dir
  174. will thus be sorted by file Name only.
  175.  
  176.      Listing types:
  177.      Directories can be listed in long, wide, or full path form.
  178.      The 'l' flag specifies Long listing.  Entries will be listed in this form:
  179. NAME   EXT   SIZE   DATE   TIME    ATTRIBUTES
  180. Subdirectory entries and the volume label always have a size of 0, so a label
  181. will be printed instead of size.  The ATTRIBUTES column gives the first letter
  182. of all of the attributes that the entry has.  For example, the IBMBIO.COM
  183. file has the attribues RHSA : read-only, hidden, system, and attribute.
  184.      The 'w' flag specifies a Wide listing.  Only the file name of the entry
  185. is printed.  If the entry is a subdirectory, a '\' is appended to the file
  186. name to indicate this.  Several names are normally printed on each line.  The
  187. number of entries printed per line is controlled by the flags '1', '2', ...
  188. '6', which specify that that many entries/line will be printed when listing in
  189. wide mode.  The names will be evenly spaced on the line.  If six entries/line
  190. is specified, there will be only one space between a file name with a full 12
  191. characters and the file name that follows it.  If the file name has 12 char-
  192. acters and the entry is a subdirectory (and thus has a '\' appended to it)
  193. there will not be any spaces at all.
  194.      The 'f' flag specifies a Full path listing.  In this case, the directory
  195. header (which normally gives the name of the directory and the number of
  196. matching files) is not printed.  Instead, the size, date, time, and attributes
  197. of each matching file are printed, followed by the full path of the file.  If
  198. the entry is a subdirectory, a '\' is appended to indicate this.  One
  199. entry/line is printed; if the full path is more than 44 characters long it will
  200. wrap around to the next line.  This type of listing is useful when a path
  201. expansion (as a result of wildcards in the directories of the path name, or
  202. the recursive search option) is done.  For example,  DI \.com /cf  will print
  203. all .com files on the disk.  No indication of the directories searched is given
  204. except as they appear in the paths of the files listed.  This prevents numerous
  205. directory headers with "0 matching files" from being printed.
  206.  
  207.      Pause:
  208.  
  209.      The 'p' flag specifies to pause after listing each screenful of entries.
  210. The internal default is no pause.  Each time the flag is found, pause is
  211. toggled.  Its final value after the environment var and command line arguments
  212. have been read determines whether pausing is done.
  213.      When output has been paused, if <space> is pressed, another screenful of
  214. listing will be displayed.  If 'q' or 'Q' is pressed, listing is aborted.  If
  215. any other key is pressed, one more line is printed and then output is paused
  216. again.
  217.  
  218.      Setting default flags:
  219.  
  220.      Default listing specifications can be given by setting the environment
  221. variable DI.  When DI is run, it first checks to determine if this variable
  222. exists.  If so, the string that it is set to is interpreted almost exactly
  223. like arguments on the command line.
  224.      If filespecs are given, they will replace the internal default of "*.*",
  225. though there would seem to be little call for any other default.
  226.      If attribute groups are given, they will replace the internal default of
  227. HSV (list everything except hidden, system, and volume label entries).
  228.      If the /c flag is  given, it toggles the initial setting of no recursive
  229. search.  The value that the recursive search flag has when interpretation of
  230. the variable is completed determines whether any filespecs given in the
  231. variable are searched recursively.  Recursive expansion of the filespecs
  232. given in the variable is done before the command line arguments are read, so
  233. a /c flag given on the command line can not toggle off recursive search of
  234. filespecs given in the variable, if recursive search is also specified in the
  235. variable.  Note that neither filespecs nor recursive search flag would normally
  236. be given in the variable...
  237.      Replacement of defaults set by the variable by command line arguments:
  238.      If any filespecs are given on the command line, the internal default or
  239. the default list produced from the variable is replaced.
  240.      If any attribute groups are given on the command line, the internal
  241. default or the default groups produced from the variable are replaced.
  242.      The /c (recursive search) flag will start out 'off' regardless of what was
  243. given in the variable.
  244.      The other flags act as though they had preceded the command line arguments
  245. (if any) on the command line.  Anything they set can be changed by arguments
  246. given on the command line.  For example, setting DI to  "/pf6nu /HSVD"  will
  247. change the defaults to pause; full path  listing; 6 entries/line when listing
  248. wide; sort by name only; do not print free space; and list everything that is
  249. not a hidden, system, volume label, or dir entry.  If the command
  250. DI /pw5zu /d  is given, pause will be toggled back off; a wide listing with 5
  251. entries/line will be printed; dir entries will be sorted by size; free space
  252. will be printed; and only subdirectory entries will be listed.
  253.      Environment variables are set with the SET command in DOS.  For example,
  254. to set the defaults to pause, and print wide with 6 entries/line, issue the
  255. command:  SET DI=/pw6
  256.  
  257.      Headers:
  258.  
  259.      Before any directories are printed, the volume labels and, depending on
  260. the -u flag, the free space are normally printed for all drives that were
  261. specified in any filespec, including the default drive if appropriate.  The
  262. -k flag can be used to suppress printing of this header as well as the headers
  263. for each directory.
  264.      The header printed for each directory normally includes the total space
  265. used by the files listed for that directory.  If the free space listing has
  266. been toggled off, printing of the total space used is also turned off because
  267. the same sometimes time-consuming operations are performed when determining
  268. the space used.  The space used is the sum of the space used by all of the
  269. sectors allocated to the files; files do not usually exactly fill the space
  270. allocated to them so the total space used will generally be larger than the
  271. sum of all of the file sizes.  The space used is rounded up to the nearest
  272. 1k; most disk formats except single-sided floppies allocate storage in
  273. multiples of 1k so this will not normally have any effect.
  274.  
  275.      Defaults:
  276.  
  277.      The internal defaults are:
  278.      Filespec : "*.*".  Pause after each page: No.  Listing type: Long.
  279. Number of entries/line to print if listing wide: 5.  Recursive search: No.
  280. First sort: By dir attribute.  Print free space on device in heading: Yes.
  281. File attributes to search for: List all files that are not hidden, system, or
  282. volume label entries.  Print headers: Yes.
  283.  
  284.      Flag summary:
  285.      Pause during listing;  list Long, Wide, or with Full path;
  286. print 1-6 entries / line if listing wide;  search directories reCursively;
  287. sort first by dIr attrib, eXtension, Time and date, siZe, or Name only;
  288. Kill headers;  print Unused (free) space on device in heading;
  289. print files with attribs: Everything (print all files), or
  290. Read only, Hidden, System, Directory, Volume label, Archive.
  291.  
  292.      Revision history:
  293.      v 1.0    8/87
  294.      v 1.1 11/8/87:
  295.         Changed format of full path listing;
  296.         Added -u option;
  297.         Added printout of total space used by files.
  298.      v 1.11 11/13/87:
  299.         Added -k option.
  300.  
  301.     Send bug reports, comments and suggestions to
  302.     John DuBois, spcecdt@ucscb.ucsc.edu
  303.